<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.ui.CommandLine</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_ui doc_api_ui_command_line'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../../'>Howl 0.3 Documentation</a></li><li>Api</li><li>Ui</li><li>howl.ui.CommandLine</li></ol>
      <h1 id="howl.ui.commandline">howl.ui.CommandLine</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.ui.CommandLine</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#properties" class="toc-group-header properties">Properties</a>
<li class=""><a href="#prompt">prompt</a></li>
<li class=""><a href="#text">text</a></li>
<li class=""><a href="#title">title</a></li>
</div>
<div class="toc-group">
<a href="#methods" class="toc-group-header methods">Methods</a>
<li class=""><a href="#add_widget">add_widget </a></li>
<li class=""><a href="#clear">clear </a></li>
<li class=""><a href="#clear_all">clear_all </a></li>
<li class=""><a href="#clear_notification">clear_notification </a></li>
<li class=""><a href="#notify">notify </a></li>
<li class=""><a href="#pop_spillover">pop_spillover </a></li>
<li class=""><a href="#remove_widget">remove_widget </a></li>
<li class=""><a href="#write">write </a></li>
<li class=""><a href="#write_spillover">write_spillover </a></li>
</div>
</div>
</div>
&#x000A;&#x000A;<p>Instances of <code>CommandLine</code> are used to control the command line widget to obtain&#x000A;user input while running an <a href="../interact.html">interaction</a>. Each <a href="window.html">Window</a>&#x000A;instance has an associated <a href="window.html#command_line">.command_line</a> field which&#x000A;is used to access the command line instance.</p>&#x000A;&#x000A;<p><a href="../interact.html">Interactions</a> work closely with the command line to obtain user input - the&#x000A;command line API is used from within a running interaction to update things like&#x000A;the displayed prompt. When no interaction is running the command line&#x000A;functionality is not available.</p>&#x000A;&#x000A;<p>Using the command line API is essential only when implementing new interactions.&#x000A;Various <a href="../interact.html#built-in-interactions">built-in interactions</a> can be&#x000A;used to obtain user input and should be preferred where applicable.</p>&#x000A;&#x000A;<p>The command line maintains a stack of running interactions. Whenever an&#x000A;interaction is started, the new interaction is <em>pushed</em> onto the stack of&#x000A;running interactions. When an interaction finishes, it is popped off the stack.&#x000A;The command line maintains state for each running interaction independently. The&#x000A;topmost interaction on the stack is called the <em>active</em> interaction.</p>&#x000A;&#x000A;<p>The command line view contains the following widgets:</p>&#x000A;&#x000A;<ul>&#x000A;<li><p>Command text entry: This is the primary text input widget that holds the&#x000A;cursor while the command line is displayed. It shows both the <em>prompt</em> and the&#x000A;<em>text</em>. The <em>prompt</em> is text set via code that is not user editable and&#x000A;displayed before the <em>text</em>, which is editable text entered by the user. When&#x000A;multiple interactions are running, the prompt and text for each is displayed&#x000A;from left to right, however only the active interaction text (i.e. the rightmost&#x000A;text) is editable.</p></li>&#x000A;<li><p>Title bar: This contains an optional title for the command line view. See&#x000A;<a href="#title"><code>title</code></a>.</p></li>&#x000A;<li><p>Notification bar: This displays notification messages. See&#x000A;<a href="#notify"><code>notify</code></a>.</p></li>&#x000A;<li><p>Custom widgets: Widgets such as <a href="list_widget.html">ListWidget</a> or <a href="notification_widget.html">NotificationWidget</a> can be&#x000A;displayed using <a href="#add_widget"><code>add_widget</code></a> and&#x000A;<a href="#remove_widget"><code>remove_widget</code></a>.</p></li>&#x000A;</ul>&#x000A;&#x000A;<hr>&#x000A;&#x000A;<p><em>See also</em>:</p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="../interact.html">interact</a> module for more information about&#x000A;interactions</li>&#x000A;<li>The <a href="../../spec/ui/command_line_spec.html">spec</a> for CommandLine</li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="properties">Properties</h2>&#x000A;&#x000A;<h3 id="prompt">prompt</h3>&#x000A;&#x000A;<p>The prompt shown in the command line. This property gets or sets the prompt for&#x000A;the active interaction. Read/write.</p>&#x000A;&#x000A;<h3 id="text">text</h3>&#x000A;&#x000A;<p>The user editable text currently in the command line. This property gets or sets&#x000A;the text for the active interaction. Read/write.</p>&#x000A;&#x000A;<h3 id="title">title</h3>&#x000A;&#x000A;<p>The title of the CommandLine view. This property only gets or sets the title for&#x000A;the active interaction. Read/write.</p>&#x000A;&#x000A;<h2 id="methods">Methods</h2>&#x000A;&#x000A;<h3 id="add_widget">add_widget <span class="arg-list">(name, widget)</span></h3>&#x000A;&#x000A;<p>Adds a custom widget <code>widget</code> in the command line view. <code>name</code> is the name used&#x000A;to identify the widget. Widgets added are associated with the active interaction&#x000A;and when the active interaction finishes, the associated widgets are&#x000A;automatically removed. Currently two types of widgets are available - widgets&#x000A;must be an instance of either <a href="list_widget.html">ListWidget</a> or <a href="notification_widget.html">NotificationWidget</a>. Widgets may&#x000A;provide their own <a href="../bindings.html">keymap</a>. The keymap for the active&#x000A;interaction takes precedence over keymaps for the attached widgets.</p>&#x000A;&#x000A;<h3 id="clear">clear <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Clears the text part of the command line. The prompt is left intact.</p>&#x000A;&#x000A;<h3 id="clear_all">clear_all <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Clears the entire command line, including any prompts and texts from other&#x000A;running interactions. When the active interaction exits, the prompts and texts&#x000A;from other running interactions are automatically restored.</p>&#x000A;&#x000A;<h3 id="clear_notification">clear_notification <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Clears any notification messages displayed, if any, and hides the notification&#x000A;bar.</p>&#x000A;&#x000A;<h3 id="notify">notify <span class="arg-list">(text, level=&lsquo;info&rsquo;)</span></h3>&#x000A;&#x000A;<p>Shows the notification bar containing the <code>text</code> message. The <code>level</code> can be&#x000A;&lsquo;info&rsquo;, &lsquo;warn&rsquo; or &lsquo;error&rsquo; and the message is styled accordingly.</p>&#x000A;&#x000A;<h3 id="pop_spillover">pop_spillover <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Returns and clears any unprocessed spillover text. See&#x000A;<a href="#write_spillover">write_spillover</a> for a description of spillover.</p>&#x000A;&#x000A;<h3 id="remove_widget">remove_widget <span class="arg-list">(name)</span></h3>&#x000A;&#x000A;<p>Removes the widget identified by <code>name</code> from the command line view.</p>&#x000A;&#x000A;<h3 id="write">write <span class="arg-list">(text)</span></h3>&#x000A;&#x000A;<p>Appends <code>text</code> to the current text in the command line. This affects the text&#x000A;for the active interaction only.</p>&#x000A;&#x000A;<h3 id="write_spillover">write_spillover <span class="arg-list">(text)</span></h3>&#x000A;&#x000A;<p>Saves <code>text</code> as the current <em>spillover</em>. The spillover is the part of the text&#x000A;that is left unprocessed by the current interaction but may be processed by&#x000A;another interaction that is invoked. There is only one spillover for the command&#x000A;line.</p>&#x000A;&#x000A;<p>For example, if the text &lsquo;open path/to/folder&rsquo; is pasted into the command line,&#x000A;the active interaction may only process &lsquo;open&rsquo; and write &lsquo;path/to/folder&rsquo; to&#x000A;spillover before invoking other interactions. An invoked interaction might then&#x000A;use <code>pop_spillover</code> to retrieve &lsquo;path/to/folder&rsquo; and process it.</p>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2015
            <a class='alert-link' href='https://github.com/nilnor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
